.\" This file is dual-licensed.  Choose whichever you want.
.\"
.\" The first licence is a regular 2-clause BSD licence.  The second licence
.\" is the CC-0 from Creative Commons. It is intended to release Monocypher
.\" to the public domain.  The BSD licence serves as a fallback option.
.\"
.\" SPDX-License-Identifier: BSD-2-Clause OR CC0-1.0
.\"
.\" ----------------------------------------------------------------------------
.\"
.\" Copyright (c) 2019-2020 Fabio Scotoni
.\" All rights reserved.
.\"
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" ----------------------------------------------------------------------------
.\"
.\" Written in 2019-2020 by Fabio Scotoni
.\"
.\" To the extent possible under law, the author(s) have dedicated all copyright
.\" and related neighboring rights to this software to the public domain
.\" worldwide.  This software is distributed without any warranty.
.\"
.\" You should have received a copy of the CC0 Public Domain Dedication along
.\" with this software.  If not, see
.\" <https://creativecommons.org/publicdomain/zero/1.0/>
.\"
.Dd March 31, 2020
.Dt CRYPTO_IETF_CHACHA20 3MONOCYPHER
.Os
.Sh NAME
.Nm crypto_ietf_chacha20 ,
.Nm crypto_ietf_chacha20_ctr
.Nd IETF Chacha20 encryption functions
.Sh SYNOPSIS
.In monocypher.h
.Ft void
.Fo crypto_ietf_chacha20
.Fa "uint8_t *cipher_text"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[12]"
.Fc
.Ft uint32_t
.Fo crypto_ietf_chacha20_ctr
.Fa "uint8_t *cipher_text"
.Fa "const uint8_t *plain_text"
.Fa "size_t text_size"
.Fa "const uint8_t key[32]"
.Fa "const uint8_t nonce[12]"
.Fa "const uint32_t ctr"
.Fc
.Sh DESCRIPTION
These functions provide an interface for the Chacha20 encryption
primitive as specified by the IETF in RFC 8439.
They are provided strictly for compatibility with existing systems
or strict standards compliance.
New programs are strongly encouraged to use
.Xr crypto_xchacha20 3monocypher
instead.
.Pp
Chacha20 is a low-level primitive.
Consider using authenticated encryption, implemented by
.Xr crypto_lock 3monocypher .
.Pp
The
.Fn crypto_ietf_chacha20
and
.Fn crypto_ietf_chacha20_ctr
functions behave the same as
.Xr crypto_chacha20
and
.Xr crypto_chacha20_ctr ,
respectively,
but use differently-sized nonce and counter values.
The nonce encompasses 12 bytes and the counter is correspondingly
reduced to 4 bytes.
The short counter limits a single pair of key and nonce to 256 GiB of
data.
A nonce of 12 bytes is
.Em just barely too short
to be safely chosen at random;
use a message counter instead.
RFC 8439 also permits linear feedback shift registers to generate
nonces.
.Sh RETURN VALUES
.Fn crypto_ietf_chacha20
returns nothing.
.Fn crypto_ietf_chacha20_ctr
returns the next
.Fa ctr
to use with the same key and nonce values;
this is always
.Fa text_size
divided by 64;
plus one if there was a remainder.
.Sh SEE ALSO
.Xr crypto_chacha20 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement Chacha20 as described in RFC 8439.
.Sh HISTORY
.Fn crypto_ietf_chacha20
and
.Fn crypto_ietf_chacha20_ctr
were added in Monocypher 3.0.0.
.Sh SECURITY CONSIDERATIONS
These functions exhibit a nonce reuse issue if the internal counter
overflows, losing all confidentiality for the parts of the data for
which the nonces overlap.
When using crypto_ietf_chacha20(),
this occurs when encrypting more than 256 GiB of data and then
incrementing the nonce.
More specifically, this can be triggered by encrypting more than
512 bytes with crypto_ietf_chacha20_ctr() at ctr = 0xffffffff,
then encrypting a message at nonce[0]+1 and ctr = 0;
it can be observed that the keystreams are identical.
.Pp
RFC 8439 only specifies that the upper limit of data per message is
256 GiB of data for a nonce pair with a counter starting at 0.
It does not specify what actions can or should be taken when this limit
is exceeded.
Encrypting more than 256 GiB of data is therefore
.Sy undefined behaviour ;
Monocypher may change the way it handles counter overflows at any time.
